Creating a Job Object for a Printable Document(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 2 - Core Printing Features / Using Core Printing Features

Creating a Job Object for a Printable Document
For each printable document that a user creates, your application needs to create a corresponding job object. Generally, you should manage job objects on a one-to-one basis with documents. An introduction to manipulating the job object in response to user actions is discussed in the chapter "Introduction to Printing With QuickDraw GX" in this book. Properties of the job object are described in "Job Object Properties" on page 2-5.
Listing 2-1 shows the MyNewDocument1 function that creates a job object for a printable document and initializes a MyDocumentRec structure. The docName parameter of the MyNewDocument1 function is a Pascal string containing the name of the document, and the myDocument parameter is a pointer to a MyDocumentRec structure. In this example, the document is simplified to handle a maximum of 20 pages.
Listing 2-1 Creating a job object for a printable document
#define kMaxPages    20

OSErr MyNewDocument1(Str31 docName, MyDocumentPtr myDocument)
{  
   OSErr    err;
   Rect     bounds;

   myDocument->numPages = 0;        /* there are no pages yet */
   myDocument->curPage = 0;

   /* Create a new job */
   err = GXNewJob(&myDocument->documentJob); 

   if (err == noErr)
   {
      /* 
         Install your application override for the
         gxPrintingEvent message to display QuickDraw GX movable
         modal dialog boxes.
      */
      GXInstallApplicationOverride(myDocument->documentJob, 
                                    gxPrintingEvent,
                                    MyPrintingEventOverride);

      /*
         Store the document's name. Limit is 31 characters (plus
         a length byte).
      */
      if (docName[0] > 31)
         docName[0] = 31;
      BlockMove(&docName[0], &myDocument->documentTitle[0], 
               (long) docName[0] +1);

      /*
         Additional application-specific document initialization
         can go here, such as the following:
         Create a window and a view port for the document. Store
         the pointer to the MyDocumentRec structure in the
         window's refCon field.
      */
      SetRect(&bounds, 30, 60, 300, 400);
      myDocument->documentWindow = NewCWindow(nil, &bounds, 
                  docName, false, noGrowDocProc, (WindowPtr) -1,
                  true, (long) myDocument);
      err = MemError();
      if (err == noErr)
      {
         SetPort(myDocument->documentWindow);
         myDocument->documentViewPort = 
         GXNewWindowViewPort(myDocument->documentWindow);
         err = GXGetGraphicsError(nil);
         
         if (err != noErr)
         DisposeWindow(myDocument->documentWindow);
      }
      if (err != noErr) GXDisposeJob(myDocument->documentJob);
   }
   return err;
}
The MyNewDocument1 function sets the number of pages in the document and the current page number. Note that pages begin at 1 (not from 0 as in an array). The initial value of 0 indicates that there are none.
The GXNewJob function creates a job object for the document. If an error does not occur, the MyNewDocument1 function performs the following tasks:

Calls the GXInstallApplicationOverride function to install a function that overrides the gxPrintingEvent message. This override is needed to handle movable print dialog boxes. The GXInstallApplicationOverride function and the gxPrintingEvent message are discussed in "Supporting QuickDraw GX Print Dialog Boxes" beginning on page 2-17.
Stores the document's name by calling the BlockMove function. The name is passed into the MyNewDocument1 function.
Creates the document's window by calling the NewWindow function and makes it the focus by calling the SetPort function.
Creates a view port for the window by calling the GXNewWindowViewPort function. This view port is used to draw individual shapes on a page and is discussed in the section "Printing Pages by Capturing Shapes" beginning on page 2-22. For information about the GXNewWindowViewPort function, see the environment chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.

In the event of an error, the job and window are disposed of, if necessary.